home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / p_man / cat3 / libelfutil / xlate_init_fd.z / xlate_init_fd
Text File  |  1998-10-30  |  18KB  |  329 lines
  1.  
  2.  
  3.  
  4. XXXXLLLLAAAATTTTEEEE____IIIINNNNIIIITTTT____FFFFDDDD((((3333EEEE))))                                            XXXXLLLLAAAATTTTEEEE____IIIINNNNIIIITTTT____FFFFDDDD((((3333EEEE))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _xxxx_llll_aaaa_tttt_eeee______iiii_nnnn_iiii_tttt______ffff_dddd: _xxxx_llll_aaaa_tttt_eeee______iiii_nnnn_iiii_tttt______eeee_llll_ffff - open translation section
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_eeee_llll_ffff_...._hhhh_>>>>
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_llll_iiii_bbbb_eeee_llll_ffff_...._hhhh_>>>>
  14.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_dddd_wwww_aaaa_rrrr_ffff_...._hhhh_>>>>
  15.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_llll_iiii_bbbb_dddd_wwww_aaaa_rrrr_ffff_...._hhhh_>>>>
  16.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_cccc_mmmm_pppp_llll_rrrr_ssss_////_xxxx_llll_aaaa_tttt_eeee_...._hhhh_>>>>
  17.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_llll_iiii_bbbb_XXXX_llll_aaaa_tttt_eeee_...._hhhh_>>>>
  18.      _iiii_nnnn_tttt _xxxx_llll_aaaa_tttt_eeee______iiii_nnnn_iiii_tttt______ffff_dddd_((((_iiii_nnnn_tttt _ffff_dddd_,,,,
  19.        _iiii_nnnn_tttt _oooo_pppp_eeee_nnnn______dddd_eeee_bbbb_uuuu_gggg______tttt_aaaa_bbbb_llll_eeee_,,,,
  20.        _xxxx_llll_aaaa_tttt_eeee______tttt_aaaa_bbbb_llll_eeee______cccc_oooo_nnnn  _****_rrrr_eeee_tttt_uuuu_rrrr_nnnn_eeee_dddd______tttt_aaaa_bbbb_llll_eeee______pppp_oooo_iiii_nnnn_tttt_eeee_rrrr_))))_;;;;
  21.      _iiii_nnnn_tttt _xxxx_llll_aaaa_tttt_eeee______iiii_nnnn_iiii_tttt______eeee_llll_ffff_((((_EEEE_llll_ffff _****_eeee_llll_ffff______hhhh_aaaa_nnnn_dddd_llll_eeee_,,,,
  22.        _iiii_nnnn_tttt _oooo_pppp_eeee_nnnn______dddd_eeee_bbbb_uuuu_gggg______tttt_aaaa_bbbb_llll_eeee_,,,,
  23.        _xxxx_llll_aaaa_tttt_eeee______tttt_aaaa_bbbb_llll_eeee______cccc_oooo_nnnn _****_rrrr_eeee_tttt_uuuu_rrrr_nnnn_eeee_dddd______tttt_aaaa_bbbb_llll_eeee______pppp_oooo_iiii_nnnn_tttt_eeee_rrrr_))))_;;;;
  24.      _iiii_nnnn_tttt _xxxx_llll_aaaa_tttt_eeee______nnnn_aaaa_mmmm_eeee_dddd______iiii_nnnn_iiii_tttt______ffff_dddd_((((_iiii_nnnn_tttt _ffff_dddd_,,,,
  25.        _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _**** _xxxx_llll_aaaa_tttt_eeee______ssss_eeee_cccc_tttt_iiii_oooo_nnnn______nnnn_aaaa_mmmm_eeee_,,,,
  26.        _xxxx_llll_aaaa_tttt_eeee______tttt_aaaa_bbbb_llll_eeee______cccc_oooo_nnnn  _****_rrrr_eeee_tttt_uuuu_rrrr_nnnn_eeee_dddd______tttt_aaaa_bbbb_llll_eeee______pppp_oooo_iiii_nnnn_tttt_eeee_rrrr_))))_;;;;
  27.      _iiii_nnnn_tttt _xxxx_llll_aaaa_tttt_eeee______nnnn_aaaa_mmmm_eeee_dddd______iiii_nnnn_iiii_tttt______eeee_llll_ffff_((((_EEEE_llll_ffff _****_eeee_llll_ffff______hhhh_aaaa_nnnn_dddd_llll_eeee_,,,,
  28.        _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _**** _xxxx_llll_aaaa_tttt_eeee______ssss_eeee_cccc_tttt_iiii_oooo_nnnn______nnnn_aaaa_mmmm_eeee_,,,,
  29.        _xxxx_llll_aaaa_tttt_eeee______tttt_aaaa_bbbb_llll_eeee______cccc_oooo_nnnn _****_rrrr_eeee_tttt_uuuu_rrrr_nnnn_eeee_dddd______tttt_aaaa_bbbb_llll_eeee______pppp_oooo_iiii_nnnn_tttt_eeee_rrrr_))))_;;;;
  30.  
  31. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  32.      These are used to get (open) a handle on an Elf section containing
  33.      translation information.  The handle allows one to call any of the
  34.      consumer functions.  it is unspecified which
  35.  
  36.      xxxxllllaaaatttteeee____iiiinnnniiiitttt____ffffdddd takes as arguments:
  37.  
  38.      _f_d      is an IRIX file-descriptor which must be open(2) for reading on
  39.              an Elf object file.
  40.  
  41.      _o_p_e_n__d_e_b_u_g__t_a_b_l_e
  42.              indicates which translation section to open.  If
  43.              _X_L_A_T_E__O_P_E_N__S_T_D__T_A_B_L_E (0), then the first section with _s_h__t_y_p_e
  44.              _S_H_T__M_I_P_S__X_L_A_T_E is opened.  If _X_L_A_T_E__O_P_E_N__S_T_D__T_A_B_L_E (1), then the
  45.              first section with _s_h__t_y_p_e _S_H_T__M_I_P_S__X_L_A_T_E__D_E_B_U_G is opened.
  46.              _X_L_A_T_E__O_P_E_N__S_T_D__T_A_B_L_E is the table normally opened by debuggers
  47.              and other applictions needing to do address translations.  Only
  48.              sections with Elf section type _S_H_T__M_I_P_S__X_L_A_T_E,
  49.              _S_H_T__M_I_P_S__X_L_A_T_E__D_E_B_U_G, or _S_H_T__M_I_P_S__X_L_A_T_E__O_L_D can be opened.
  50.  
  51.      _r_e_t_u_r_n_e_d__t_a_b_l_e__p_o_i_n_t_e_r
  52.              is a pointer to a consumer table handle.  If the call to
  53.              _x_l_a_t_e__i_n_i_t__f_d is successful, the handle pointed to is set a valid
  54.              consumer library handle.
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.                                                                         PPPPaaaaggggeeee 1111
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68. XXXXLLLLAAAATTTTEEEE____IIIINNNNIIIITTTT____FFFFDDDD((((3333EEEE))))                                            XXXXLLLLAAAATTTTEEEE____IIIINNNNIIIITTTT____FFFFDDDD((((3333EEEE))))
  69.  
  70.  
  71.  
  72.      xxxxllllaaaatttteeee____iiiinnnniiiitttt____eeeellllffff takes as arguments:
  73.  
  74.      _e_l_f__h_a_n_d_l_e
  75.              which must be a valid open pointer on an existing Elf object as
  76.              returned by _e_l_f__b_e_g_i_n(3e) and it must allow read access.
  77.  
  78.      _o_p_e_n__d_e_b_u_g__t_a_b_l_e
  79.              indicates which translation section to open.  If
  80.              _X_L_A_T_E__O_P_E_N__S_T_D__T_A_B_L_E (0), then the first section with _s_h__t_y_p_e
  81.              _S_H_T__M_I_P_S__X_L_A_T_E is opened.  If _X_L_A_T_E__O_P_E_N__S_T_D__T_A_B_L_E (1), then the
  82.              first section with _s_h__t_y_p_e _S_H_T__M_I_P_S__X_L_A_T_E__D_E_B_U_G is opened.
  83.              _X_L_A_T_E__O_P_E_N__S_T_D__T_A_B_L_E is the table normally opened by debuggers
  84.              and other applictions needing to do address translations.  Only
  85.              sections with Elf section type _S_H_T__M_I_P_S__X_L_A_T_E,
  86.              _S_H_T__M_I_P_S__X_L_A_T_E__D_E_B_U_G, or _S_H_T__M_I_P_S__X_L_A_T_E__O_L_D can be opened.
  87.  
  88.      _r_e_t_u_r_n_e_d__t_a_b_l_e__p_o_i_n_t_e_r
  89.              is a pointer to a consumer table handle.  If the call to
  90.              _x_l_a_t_e__i_n_i_t__f_d is successful, the handle pointed to is set to a
  91.              valid consumer library handle.
  92.  
  93.      xxxxllllaaaatttteeee____nnnnaaaammmmeeeedddd____iiiinnnniiiitttt____ffffdddd takes as arguments:
  94.  
  95.      _f_d      is an IRIX file-descriptor which must be open(2) for reading on
  96.              an Elf object file.
  97.  
  98.      _x_l_a_t_e__s_e_c_t_i_o_n__n_a_m_e
  99.              indicates which translation section to open.  The normal string
  100.              passed in is ".MIPS.Xlate" which is the name of the net
  101.              (composed) address translation table used by debuggers and other
  102.              applictions needing to do address translations.  Any Elf section
  103.              with _s_h__t_y_p_e _S_H_T__M_I_P_S__X_L_A_T_E, _S_H_T__M_I_P_S__X_L_A_T_E__D_E_B_U_G, or
  104.              _S_H_T__M_I_P_S__X_L_A_T_E__O_L_D may be opened.
  105.  
  106.      _r_e_t_u_r_n_e_d__t_a_b_l_e__p_o_i_n_t_e_r
  107.              is a pointer to a consumer table handle.  If the call to
  108.              _x_l_a_t_e__i_n_i_t__f_d is successful, the handle pointed to is set a valid
  109.              consumer library handle.
  110.  
  111.      xxxxllllaaaatttteeee____nnnnaaaammmmeeeedddd____iiiinnnniiiitttt____eeeellllffff takes as arguments:
  112.  
  113.      _e_l_f__h_a_n_d_l_e
  114.              which must be a valid open pointer on an existing Elf object as
  115.              returned by _e_l_f__b_e_g_i_n(3e) and it must allow read access.
  116.  
  117.      _x_l_a_t_e__s_e_c_t_i_o_n__n_a_m_e
  118.              indicates which translation section to open.  The normal string
  119.              passed in is ".MIPS.Xlate" which is the name of the net
  120.              (composed) address translation table used by debuggers and other
  121.              applictions needing to do address translations.  Any Elf section
  122.              with _s_h__t_y_p_e _S_H_T__M_I_P_S__X_L_A_T_E, _S_H_T__M_I_P_S__X_L_A_T_E__D_E_B_U_G, or
  123.              _S_H_T__M_I_P_S__X_L_A_T_E__O_L_D may be opened.
  124.  
  125.  
  126.  
  127.                                                                         PPPPaaaaggggeeee 2222
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134. XXXXLLLLAAAATTTTEEEE____IIIINNNNIIIITTTT____FFFFDDDD((((3333EEEE))))                                            XXXXLLLLAAAATTTTEEEE____IIIINNNNIIIITTTT____FFFFDDDD((((3333EEEE))))
  135.  
  136.  
  137.  
  138.      _r_e_t_u_r_n_e_d__t_a_b_l_e__p_o_i_n_t_e_r
  139.              is a pointer to a consumer table handle.  If the call to
  140.              _x_l_a_t_e__i_n_i_t__f_d is successful, the handle pointed to is set to a
  141.              valid consumer library handle.
  142.  
  143.  
  144.      Use -lelfutil -lelf on the link command line to link  in the xlate
  145.      functions.
  146.  
  147.      You must install the _c_o_m_p_i_l_e_r__e_o_e._h_d_r._i_n_t_e_r_n_a_l subsystem to get the
  148.      headers necessary to work with the xlate functions and leb128 functions
  149.      they call.
  150.  
  151. FFFFIIIILLLLEEEESSSS
  152.      /usr/include/libXlate.h
  153.      /usr/include/cmplrs/xlate.h
  154.      /usr/include/elf.h
  155.      /usr/include/dwarf.h
  156.      /usr/include/libdwarf.h
  157.      /usr/lib/libelfutil.a
  158.  
  159. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  160.      These return _X_L_A_T_E__T_B__S_T_A_T_U_S__N_O__E_R_R_O_R (_0) on success.  In case of error,
  161.      a negative number is returned indicating the error.  In case of error,
  162.      nothing is returned thru the pointer arguments which would return values
  163.      on successful call (values might have been changed thru these pointers
  164.      but any such changes are not meaningful).
  165.  
  166.      If the requested section does not exist, _X_L_A_T_E__T_B__S_T_A_T_U_S__N_O__X_L_A_T_E is
  167.      returned.  This is not really an error, just an indication that there is
  168.      no such section and there is no value returned thru
  169.      _r_e_t_u_r_n_e_d__t_a_b_l_e__p_o_i_n_t_e_r.
  170.  
  171.      _X_L_A_T_E__T_B__S_T_A_T_U_S__S_E_C_T_I_O_N__T_O_O__S_M_A_L_L
  172.              means that the translation section is too small to be real or
  173.              that there is less space in the section than the translation
  174.              section data says it contains.
  175.  
  176.      _X_L_A_T_E__T_B__S_T_A_T_U_S__I_N_C_O_N_S_I_S_T_E_N_T__6_4__B_I_T__I_N_F_O
  177.              means that the translation section is marked as a 64bit section
  178.              but the a.out or DSO is marked as 32 bit (or vice versa).
  179.  
  180.      _X_L_A_T_E__T_B__S_T_A_T_U_S__B_A_D__T_A_B_L_E_K_I_N_D
  181.              The tablekind in the translation section is not one of the
  182.              predefined values: something is corrupted or an obsolete
  183.              tablekind thought not to exist does exist.
  184.  
  185.      _X_L_A_T_E__T_B__S_T_A_T_U_S__N_O_T__E_L_F
  186.              _e_l_f__k_i_n_d(3e) on the file says the file is not a plain Elf file.
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.                                                                         PPPPaaaaggggeeee 3333
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200. XXXXLLLLAAAATTTTEEEE____IIIINNNNIIIITTTT____FFFFDDDD((((3333EEEE))))                                            XXXXLLLLAAAATTTTEEEE____IIIINNNNIIIITTTT____FFFFDDDD((((3333EEEE))))
  201.  
  202.  
  203.  
  204.      _X_L_A_T_E__T_B__S_T_A_T_U_S__E_L_F__I_D_E_N_T__B_A_D
  205.              _e_l_f__g_e_t_i_d_e_n_t(3e) returns an invalid Elf ident value.  The file is
  206.              apparently not a valid Elf file.
  207.  
  208.      _X_L_A_T_E__T_B__S_T_A_T_U_S__E_L_F__S_H_D_R__B_A_D
  209.              _e_l_f_3_2__g_e_t_s_h_d_r(3e), or _e_l_f_6_4__g_e_t_s_h_d_r(3e) could not find a section
  210.              in the Elf file that should be there. Some kind of corruption
  211.              (file or data) is occurring.  The file is apparently not a valid
  212.              Elf file.
  213.  
  214.      _X_L_A_T_E__T_B__S_T_A_T_U_S__N_O__X_L_A_T_E
  215.              Normal return when there is no translation section of the
  216.              requested type.
  217.  
  218.      _X_L_A_T_E__T_B__S_T_A_T_U_S__N_O__X_L_A_T_E__D_A_T_A
  219.              There is a translation section but the section is empty!
  220.              Something is wrong with the Elf file.
  221.  
  222.      _X_L_A_T_E__T_B__S_T_A_T_U_S__A_L_L_O_C__F_A_I_L
  223.              A call to _m_a_l_l_o_c() or _r_e_a_l_l_o_c() failed.
  224.  
  225.      _X_L_A_T_E__T_B__S_T_A_T_U_S__S_E_C_T_I_O_N__T_O_O__B_I_G
  226.              The translation section is so large ( > 31 bits in the size) that
  227.              it cannot be handled by the 32-bit version of the library.  This
  228.              is quite unlikely since translation sections should be much
  229.              smaller than the text they refer to and text sections do not get
  230.              that big (as of this writing).  The application must be rebuilt
  231.              as a 64bit application and linked against a 64-bit version of
  232.              this library.
  233.  
  234.      _X_L_A_T_E__T_B__S_T_A_T_U_S__E_D_H_R__B_A_D
  235.              A call to _e_l_f_3_2__g_e_t_e_h_d_r(3) or _e_l_f_6_4__g_e_t_e_h_d_r(3) (whichever is
  236.              appropriate) failed.  The object file is damaged or the library
  237.              has a bug.
  238.  
  239.      _X_L_A_T_E__T_B__S_T_A_T_U_S__S_T_R_P_T_R__B_A_D
  240.              A call to _e_l_f__s_t_r_p_t_r(3) (whichever is appropriate) failed.  No
  241.              section name strings could be found.  The object file is
  242.              specially stripped or damaged or the library has a bug.
  243.  
  244. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  245.      libelfutil(5), open(2), xlate(4), xlate_get_info(3e), xlate_address(3e),
  246.      xlate_get_reg_rule(3e), xlate_get_all_reg_rules(3e),
  247.      xlate_expand_reg_info(3e), xlate_finish(3e), xlate_pro_init(3e),
  248.      xlate_pro_finish(3e), xlate_address(3e)
  249.  
  250. NNNNOOOOTTTTEEEESSSS
  251.      For any of these calls to succeed the section contents must also be a
  252.      valid translate section.
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.                                                                         PPPPaaaaggggeeee 4444
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266. XXXXLLLLAAAATTTTEEEE____IIIINNNNIIIITTTT____FFFFDDDD((((3333EEEE))))                                            XXXXLLLLAAAATTTTEEEE____IIIINNNNIIIITTTT____FFFFDDDD((((3333EEEE))))
  267.  
  268.  
  269.  
  270.      In case there are multiple sections of an Elf object file meeting the
  271.      section name and section type criteria above then one of the sections is
  272.      opened.
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.                                                                         PPPPaaaaggggeeee 5555
  326.  
  327.  
  328.  
  329.